클로드 코드 완벽 가이드 — 16장 UI 프로토타이핑하기 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

16장에서 다루는 내용

• 프로젝트 초기화하기 — 프레임워크 선택 기준과 Next.js + Shadcn + Tailwind 기반 프로젝트 생성
• 초기 UI 프로토타이핑하기 — PRD를 기반으로 플래닝 모드에서 계획 수립 후 UI 구현
• 동시에 여러 시안 프로토타이핑하기 — Git worktree와 subagent를 활용한 병렬 디자인 시안 생성

전체 흐름도

[프레임워크 선택]            [초기 UI 프로토타이핑]          [여러 시안 동시 생성]
    |                            |                            |
    v                            v                            v
+---------------------+  +-------------------------+  +---------------------------+
| 1. 선택 기준 2가지  |  | 1. VS Code + 클로드 코드|  | 1. git add & commit       |
|    - 내가 아는 것   |  |    터미널 실행           |  |    (초기 커밋 생성)       |
|    - 인기/대중성    |  | 2. PRD 복사 →           |  | 2. 커스텀 커맨드 작성     |
| 2. Next.js 선택     |  |    플래닝 모드에 붙여넣기|  |    .claude/commands/      |
|    (App Router)     |  |    (Shift+Tab 전환)     |  |    create-designs.md      |
| 3. Shadcn/ui 설정   |  | 3. 작업량 확인 (중요!)  |  | 3. /create-designs 실행  |
| 4. Tailwind CSS     |  |    Opus 모델 주의       |  |    4가지 테마 인수 전달   |
| 5. ESLint/Prettier  |  | 4. [Yes] → 구현 시작    |  | 4. subagent 4개가         |
+---------------------+  | 5. 초기 세팅 오류 해결  |  |    worktree별 병렬 작업   |
        |                 |    (오류 전체 복사!)     |  | 5. 각각 다른 포트로       |
        v                 +-------------------------+  |    dev 서버 실행          |
  UI 품질에 직접 영향!             |                    +---------------------------+
  대중적 프레임워크일수록          v                                |
  AI가 더 잘 만든다          PRD와 비슷한 디자인                    v
                             프로토타입 완성!              4가지 시안을 동시에
                                                           비교하고 최적안 선택

선수 지식 체크리스트

• [ ] 15장: PRD(제품 요구사항 문서) 작성법 — PRD가 있어야 UI를 만들 수 있다
• [ ] Next.js 기본 개념 (App Router, Server Components)
• [ ] 터미널/CLI 기본 사용법
• [ ] Git 기본 명령어 (add, commit)

핵심 키워드

섹션 1: 프로젝트 초기화하기

한 줄 요약

프레임워크 선택 시 "내가 아는 것"과 "대중적인 것" 2가지 기준을 고려하며, Next.js + Shadcn + Tailwind 조합이 AI 기반 UI 제작에 가장 적합하다.

쉬운 설명 (비유)

프레임워크 선택은 "요리 도구 세트" 고르기와 같다.

아무리 훌륭한 AI 셰프(클로드)라도,
익숙하지 않은 도구를 주면 실수가 많아진다.

❌ 아무도 안 쓰는 희귀한 칼 세트 → AI도 잘 못 다룸
✅ 전 세계 셰프가 쓰는 글로벌 브랜드 칼 세트 → AI가 가장 잘 다룸

Next.js = 가장 많이 쓰는 칼 세트
Shadcn  = 예쁜 그릇 세트
Tailwind = 양념 모음

→ 세 가지를 함께 쓰면 AI가 가장 맛있는 요리(UI)를 만든다!

실무 예제: 프레임워크 선택 기준 체크리스트

프레임워크 선택 2가지 핵심 기준:

[기준 1] 내가 아는 프레임워크인가?
  ❌ "처음 들어보는 프레임워크인데 AI가 다 해주겠지"
     → 버그가 나면 디버깅을 전혀 못 한다!
  ✅ "기본 구조는 알고 있어서 최소한 디버깅은 가능해"
     → 바이브 코딩이 발전해도 100% 버그 없는 건 불가능

[기준 2] 대중적인 프레임워크인가?
  ❌ Svelte (인구 적음) → AI 학습 데이터 부족
  ✅ Next.js (가장 인기) → AI가 가장 잘 만드는 UI

  핵심 포인트: AI는 학습 데이터가 많은 기술일수록 결과가 좋다.
  특히 UI 제작에서 이 차이가 가장 크게 드러난다!

핵심 체크포인트

• [ ] 프레임워크 선택의 2가지 기준: "내가 아는 것"과 "대중적인 것"
• [ ] 바이브 코딩이라도 버그 없이 한 번에 완성하는 것은 불가능하므로, 최소한의 디버깅 능력이 필요하다
• [ ] AI는 대중적인 프레임워크일수록 더 높은 품질의 UI를 생성한다
• [ ] Next.js + Shadcn + Tailwind 조합이 현재 AI 코딩에 가장 적합한 기술 스택이다
• [ ] App Router 방식의 Next.js를 사용하며, Server Component를 우선 구현한다

섹션 2: 초기 UI 프로토타이핑하기

한 줄 요약

PRD를 플래닝 모드에 붙여넣어 구현 계획을 세우고, 작업량을 확인한 뒤 [Yes]를 눌러 UI를 생성하며, 오류 발생 시 오류 전체를 복사해서 클로드에게 전달한다.

쉬운 설명 (비유)

UI 프로토타이핑은 "건축 모형 만들기"와 같다.

실제 집을 짓기 전에 → 미니어처 모형을 먼저 만든다.
실제 앱을 코딩하기 전에 → 프로토타입을 먼저 만든다.

모형의 특징:
  - 수도/전기는 안 나옴 (기능은 없음)
  - 방 배치와 동선은 볼 수 있음 (화면 구성과 흐름)
  - 마음에 안 들면 쉽게 바꿀 수 있음 (빠른 수정)

PRD = 건축 설계도
플래닝 모드 = 시공 계획서 작성
[Yes] = 시공 시작!

실무 예제: 플래닝 모드로 UI 프로토타이핑하는 4단계

[1단계] VS Code에서 클로드 코드 실행
  → 터미널에서 클로드 코드를 실행한다

[2단계] 플래닝 모드로 전환 후 PRD 붙여넣기
  → Shift + Tab 을 눌러 플래닝 모드로 전환
  → 프롬프트 작성:
     "아래 PRD를 기반으로 새로운 NextJS 프로젝트를 구성해줘.
      Shadcn, Tailwind를 사용해주고 기능은 구현하지 말고
      UI만 제작해줘. NextJS는 꼭 App Router 기반으로
      Server Component를 우선시해서 구현해줘."
  → PRD 텍스트를 붙여넣기 (Pasted text #1 +247 lines)

[3단계] 작업량 확인 (⚠️ 매우 중요!)
  → 클로드가 계획을 보여줌:
     - 1단계: 프로젝트 초기 설정 (Next.js, Tailwind, Shadcn/ui, ESLint)
     - 2단계: 프로젝트 구조 구성 (폴더/파일 구조)
     - Todo 리스트 자동 생성
  → Opus 모델은 한 번에 전체를 구현하려고 하므로 주의!
  → "UI 작업 외의 작업이 포함되지 않았는지 꼭 확인"

[4단계] [Yes] 선택 → 구현 시작
  → 계획에 문제가 없으면 Yes를 선택
  → PRD의 디자인과 광장히 비슷한 결과물이 생성됨
  → 같은 프롬프트라도 결과는 매번 다를 수 있음 (AI 특성)

실무 예제: 초기 세팅 오류 해결법

오류 해결 3단계 전략:

[전략 1] 오류 전체를 복사해서 붙여넣기 (가장 중요!)
  ❌ "bg-background 에러가 나요" (요약만 전달)
     → 클로드가 문맥을 파악하기 어렵다
  ✅ "아래 에러가 발생하고 있는데 왜 발생하고 있는지 알려줘
      --------------------------------
      Error: Cannot apply unknown utility class `bg-background`
        [at onInvalidCandidate (/Users/.../tailwindcss/...)]
        [at ge (/Users/.../tailwindcss/...)]
        ...전체 스택 트레이스..."
     → 오류 내용을 전부 복사해서 전달하면 정확한 해결책을 준다

[전략 2] 확장된 사고 기법 사용
  → 그래도 해결이 안 되면 "확장된 사고"(Extended Thinking)를 활성화
  → 클로드가 더 깊이 분석하여 해결책을 제시한다

[전략 3] Opus 모델 사용
  → 복잡한 오류는 더 강력한 Opus 모델로 전환하면 해결 확률이 높아진다

핵심 체크포인트

• [ ] 플래닝 모드는 Shift+Tab으로 전환하며, 코드를 바로 작성하지 않고 계획을 먼저 세운다
• [ ] PRD를 프롬프트에 붙여넣을 때 "기능은 구현하지 말고 UI만 제작해줘"라고 명시해야 한다
• [ ] 작업량 확인이 매우 중요하다 — Opus 모델은 한 번에 전체를 구현하려는 경향이 있다
• [ ] 오류 발생 시 인터넷 검색보다 오류 전체를 복사해서 클로드에게 전달하는 것이 효과적이다
• [ ] AI는 같은 프롬프트에도 매번 다른 결과를 생성하므로, 결과가 다를 수 있음을 인지해야 한다
• [ ] Server Component를 우선시하여 구현을 요청해야 성능과 SEO에 유리하다

섹션 3: 동시에 여러 시안 프로토타이핑하기

한 줄 요약

Git worktree와 커스텀 커맨드를 활용하여 4개의 subagent가 동시에 서로 다른 디자인 시안을 생성하고, 각각 다른 포트에서 실행하여 비교 선택한다.

쉬운 설명 (비유)

여러 시안 동시 제작은 "인테리어 업체 4곳에 동시 의뢰"하는 것과 같다.

❌ 기존 방식: 1곳에 의뢰 → 시안 확인 → 마음에 안 들면 다시 의뢰 → 반복
   → 시간이 오래 걸리고, 비교가 어렵다

✅ 새로운 방식: 4곳에 동시 의뢰 → 4가지 시안을 한꺼번에 비교 → 최적안 선택
   → 빠르고, 다양한 스타일을 비교할 수 있다

Git worktree = 같은 집에 4개의 작업실을 만드는 것
subagent     = 각 작업실에 배정된 인테리어 디자이너
커스텀 커맨드 = 4명에게 동시에 주는 작업 지시서

실무 예제: 커스텀 커맨드로 4가지 시안 동시 생성

[1단계] 초기 커밋 생성 (worktree 기반 필수)
  → git add .
  → git commit -m "초기 커밋"

[2단계] 커스텀 커맨드 파일 작성
  → 파일 경로: .claude/commands/create-designs.md
  → 내용:
     # Persona
     너는 지금부터 UI 전문가야. 현재 프로젝트의 시안을 4개 더 만들려고 해.

     # 작업
     아규먼트로 입력한 4가지 테마로 4개의 UI 시안을 제작해줘.
     4개의 시안은 모두 독립적인 subagent를 생성해서
     동시에 parallel하게 작업해줘.

     ## 각각 subagent별 작업 방법
     - worktree를 생성해줘 !`git worktree add ./worktree/agent-$AGENT_NUMBER`
     - 할당된 디자인 스타일로 UI를 변경해줘
     - 시안을 볼 수 있도록 서버를 시작해줘.
       !`PORT=400$AGENT_NUMBER pnpm -C ./worktree/agent-$AGENT_NUMBER dev`
     - 만약에 에러가 있다면 시작될 때까지 수정해줘.

[3단계] 커맨드 실행
  → /create-designs 미니멀 테마, 네온 사이버 테마, 네이처 테마, 럭셔리 테마

[4단계] 결과 확인
  → 4개의 서버가 각각 다른 포트(4001, 4002, 4003, 4004)에서 실행
  → 브라우저에서 4가지 시안을 동시에 비교
  → 마음에 드는 시안을 선택하여 메인 프로젝트에 반영

실무 예제: 프롬프트에서 영어를 섞는 이유

중간중간 영어를 섞는 이유 = 더 정확한 지시를 위해서!

❌ "병렬로 작업해줘"
   → 한국어만으로는 의미가 약간 모호할 수 있음

✅ "모두 독립적인 subagent를 생성해서 동시에 parallel하게 작업해줘"
   → 기술 용어는 영어가 더 정확하게 전달됨

이유: 클로드(LLM)는 영어 기반으로 학습되었으므로,
기술적 지시사항은 영어를 섞어 쓰면 더 정확하게 이해한다.

핵심 체크포인트

• [ ] 여러 시안을 만들려면 먼저 git commit으로 초기 상태를 저장해야 한다
• [ ] 커스텀 커맨드는 .claude/commands/ 폴더에 마크다운 파일로 저장한다
• [ ] Git worktree를 사용하면 브랜치 전환 없이 여러 작업 디렉토리를 동시에 운영할 수 있다
• [ ] subagent는 독립적인 하위 에이전트로, 서로 간섭 없이 병렬 작업이 가능하다
• [ ] 각 시안은 서로 다른 포트(4001~4004)에서 dev 서버를 실행하여 동시에 비교한다
• [ ] 프롬프트에서 기술 용어는 영어를 섞어 쓰면 AI가 더 정확하게 이해한다
• [ ] AI는 같은 프롬프트에도 매번 다른 결과를 생성하므로, 결과가 다를 수 있음을 인지해야 한다

연습문제

문제 1 (기본)

프레임워크를 선택할 때 고려해야 하는 2가지 핵심 기준은 무엇인가? 각각의 이유를 설명하라.

문제 2 (중급)

플래닝 모드에서 PRD를 기반으로 UI를 만들 때, "작업량을 정확히 확인하는 게 매우 중요하다"고 강조하는 이유는 무엇인가? 특히 Opus 모델 사용 시 어떤 문제가 발생할 수 있는지 구체적으로 설명하라.

문제 3 (중급)

초기 세팅 과정에서 오류가 발생했을 때, 인터넷 검색보다 클로드 코드에 오류를 전달하는 방식이 더 효과적인 이유를 설명하고, 올바른 오류 전달 방법을 설명하라.

문제 4 (심화)

Git worktree와 subagent를 활용하여 4가지 디자인 시안을 동시에 생성하는 전체 과정을 단계별로 설명하라. 커스텀 커맨드 파일의 핵심 구성요소도 포함하라.

부록 A: 용어 사전

부록 B: 비교표

UI 프로토타이핑 vs 실제 앱 개발

프레임워크 선택 가이드

단일 시안 vs 동시 다중 시안 비교

부록 C: 참고 자료